APIV4 changes.txt

   1 API changes R3->R4
   2
   3 Header files:
   4 All header files have had 4 appended to their name. The R4 files are called:
   5 VapourSynth4.h
   6 VSHelper4.h
   7 VSScript4.h
   8 VSConstants4.h
   9 Where the constants one is new and has all the constants used for frame properties but aren't needed
  10 to use the basic api.
  11
  12 Constant names:
  13 A lot of the enums have changed prefixed. For example cm => cf, pa => ma and so on.
  14
  15 Video format:
  16 Video formats are no longer pointers that can be compared for equivalence. Instead the full struct
  17 is passed around. Format ids have also been converted to a uin32_t that stores all the same information.
  18 Note that you still have to use the api to unpack it since otherwise v3 format ids won't be correctly
  19 interpreted.
  20
  21 Core creation:
  22 createCore() now takes a set of flags instead of a thread number since it can be set directly after
  23 construction with setThreadCount() anyway. The flags control the few options that have to be set at
  24 creation time and can't be changed later.
  25
  26 Plugin and function registration:
  27 There's a completely new entry point called VapourSynthPluginInit2 with a different definition.
  28 The relevant functions are now passed as function pointers in a struct like the main api.
  29 Things mostly work the same but configPlugin() now takes an additional argument for the plugin
  30 version number. It's recommended to use the VS_MAKE_VERSION macro for this. The "read only" field
  31 has now been turned into a flags field where 0 is the new default value to make a plugin read only.
  32 The flag pcModifiable has been introduced to get the R3 api behavior of passing 0.
  33
  34 Function registrations now take an additional argument for the return type that follows the same
  35 format as the input arguments. If a function has an unknown or simple unpredictable return type
  36 it can be set to "any". Note that R3 functions will have the "any" return type.
  37 Since the audio types anode and a frame were introduced the video counterparts were renamed to
  38 vnode and vframe instead of clip and frame.
  39
  40 VSMap/property manipulation:
  41 All functions starting with prop* have been renamed to map*. Likewise get/setError has been renamed to
  42 mapGet/SetError for greater consistency.
  43 The paTouch mode has been removed and mapSetEmpty should be used instead in the rare cases where
  44 it's needed.
  45 Audio node and audio frame types were added and the types are now declared as normal enum constants
  46 and not obscure characters. The best way to think about audio and video nodes are that they're two
  47 separate types that happen to share functions to manipulate them. As a result of this reasoning a
  48 single key in a VSMap can only hold audio or video nodes but not a mix of both. The same applies to
  49 frames (but they're rarely used as arguments).
  50 The data type now has a hint for whether the data should be treated as utf8 or binary which can be
  51 useful for filters that print values. Data set by R3 filters will always be reported as unknown.
  52 Two new convenience functions were added. mapGetSaturatedInt and mapGetSaturatedFloat which are
  53 equivalent to int64ToIntS(propGetInt) and the same operation for float.
  54
  55 Filter changes:
  56 createFilter has been replaced by createVideoFilter. The init callback has been deprecated and instead
  57 VSVideoInfo is passed directly to createVideoFilter. Flags have been reworked and nfNoCache has been
  58 replaced by the dependency listing. This is simply an array of the nodes used as input and whether
  59 or not requests from them are strictly spatial. Note that if you take two different length clips as
  60 input you may request the final frame of the shorter clip very many times and violate the strictly
  61 spatial flag.
  62 The nfMakeLinear flag has been replaced by the two api functions setLinearFilter and cacheFrame
  63 which allows filters to push not requested frames into the cache. See FFMS2 and AVISource for
  64 examples of this.
  65 The getFrame callback has also been changed in two important ways, the void **instanceData pointer
  66 has been changed to void * to remove the pointless additional indirection. The void **frameData
  67 pointer now points to a scratch space of size void *[4] instead of only being a single pointer.
  68 This can be used to not have to allocate and free memory on every frame processed. See the Splice
  69 filter for an example of this.
  70 The arFrameReady event has been completely removed since nobody used it.
  71 Likewise YCoCg has been removed as a separate color family and is now simply considered to be YUV matrix.
  72
  73 Audio filter support:
  74 Audio filters are created with createAudioFilter and work very similarly to video filters. Note that
  75 all audio frames have a fixed size (VS_AUDIO_FRAME_SAMPLES) except for the last one in a clip that may
  76 be shorter if necessary. This needs to be kept in mind when writing filters that append two clips.
  77
  78 Message handlers:
  79 Message handlers are now registered per core and not globally to improve core and environment isolation.
  80 Note that there's no longer a default handler that prints messages to stderr if no handler is installed
  81 so direct users of the core/vsscript need to install one to still get messages printed.
  82 There's also a new mtInformation level that's self-explanatory.
  83
  84 VSHelper:
  85 The header now has all functions placed in the vsh namespace (C++) or prefixes them with vsh (C) in
  86 order to not clutter things up as much. Several functions were also renamed for clarity.
  87 Renamed functions:
  88 all functions with a vs_ prefix had it removed (see C/C++ mode differences above)
  89 isSameFormat => isSameVideoInfo (IMPORTANT! do not confuse with the new function called isSameVideoFormat)
  90 isConstantFormat => isConstantVideoFormat
  91 vs_aligned_malloc => vsh_aligned_malloc
  92 vs_aligned_free => vsh_aligned_free
  93 VS_ALIGNED_MALLOC => VSH_ALIGNED_MALLOC
  94 VS_ALIGNED_FREE => VSH_ALIGNED_FREE
  95 vs_normalizeRational => reduceRational
  96
  97 VSScript:
  98 The api is mostly the same with the exception that createScript() has to be manually called in all cases and the API
  99 now uses a struct of function pointers. It's also possible to pass a pre-created core to createScript() in order to set
 100 options such as logging output before script evaluation.
 101 VSScript also no longer changes the working directory by default when evaluating scripts. This option
 102 has been removed due to it involving global state.
 103
 104 Python changes:
 105 Multiple constants such as YCOCG have been dropped since they no longer exist in the C API.
 106 Many deprecated functions like get_core() have been removed. Note that these functions have been deprecated since at
 107 least R51 and usually much longer ago and therefore shouldn't cause problems.
 108 Frame data access has been reworked and the broken get_read_array and get_write_array functions have been dropped.
 109 They're replaced by frame[plane/channel] which will return a python array to access the underlying data directly without
 110 a risk of access violations.